Getting started

In deze sectie doorlopen we de stappen om een eigen API op te zetten en leer je hoe je zowel de API als de interactieve documentatie gebruikt met behulp van een voorbeeldproject.

1. Maak een project ID aan

Op de homepagina kun je je registreren je met je NOVI student-e-mailadres. Na registratie ontvang je per e-mail een unieke Project ID. Deze heb je nodig om toegang te krijgen tot jouw eigen, persoonlijke omgeving. Bewaar deze goed.

2. Maak een database-configuratie-bestand

Maak een bestand aan op jouw computer met een .json-extensie. Open dit bestand vervolgens met WebStorm en plak jouw database-configuratie erin. Als dit de eerste keer is dat je deze API gebruikt, kun je om te beginnen deze JSON-voorbeeld-configuratie voor een online bibliotheek gebruiken. Deze vervang je later door je eigen databaseontwerp.

3. Upload je gegevens

Op de homepagina kun je jouw Project ID invullen en het JSON-configuratiebestand uploaden. Zodra je dit hebt gedaan, wordt je API direct gegenereerd en krijg je toegang tot de interactieve documentatie via Swagger UI via de ' Bekijk Swagger UI'-knop klikken.

Hoe gebruik ik de API?

Wanneer de interactieve documentatie gegenereerd is, is de API klaar voor gebruik op de volgende base URL die verreikt kan worden met de beschikbare endpoints:

BASE URL

https://novi-backend-api-wgsgz.ondigitalocean.app/

Let er bij het gebruik van de API op dat je de juiste poort gebruikt om je frontend te draaien. Dit moet op localhost 5173 of 3000, anders krijg je CORS-errors. Hier kan je meer lezen over wat CORS is en wat een CORS-error precies inhoudt.

Omdat meerdere studenten tegelijkertijd met hun eigen API-configuratie werken, is het nodig om jouw unieke Project ID mee te sturen bij requests. Hiermee weet het systeem precies welke database en instellingen bij jouw project horen. Je stuurt jouw ID bij ieder request mee onder de naam novi-education-project-id in de request-header:

{
  'novi-education-project-id': 'xxx-xxx-xxxx-xxx'
}

Wanneer je een verzoek wil doen naar een afgeschermd endpoint, zul je daarnaast ook een JWT-token mee moeten sturen onder de naam Authorization in de request-header:

{
  'Authorization': 'Bearer xxx.xxx.xxx'
}

Je verkrijgt een JWT-token door een bestaande gebruiker in te loggen via het POST /api/login endpoint. Of een endpoint openbaar of afgeschermd is, bepaal je zelf in jouw configuratie-bestand.

Hoe gebruik ik de Swagger UI?

De Swagger UI geeft je een visuele, klikbare weergave van de API. Hiermee kun je makkelijk ontdekken welke endpoints er zijn en ze direct uitproberen. Ideaal om mee te testen voordat je je frontend-app eraan koppelt.

In de Swagger sectie staat uitgebreid uitgelegd hoe je Swagger UI kunt gebruiken om op een eenvoudige manier je API te testen.

Wat staat er in het configuratiebestand?

Hoewel je in de komende secties stap voor stap leert hoe je zelf een configuratiebestand opzet, kan het helpen om eerst een kijkje te nemen in het configuratiebestand van de online bibliotheek. Dit voorbeeld laat goed zien hoe je verschillende soorten collecties, relaties en toegangsrechten kunt instellen. Het bestand begint met collecties en hun velden:

  • Books – boeken die uitleenbaar zijn. Elk boek moet een titel, ISBN, prijs, beschikbaarheidsstatus, en verwijzingen naar een auteur en genre bevatten.
  • Authors – schrijvers van de boeken krijgen een naam en korte biografie. Deze zijn expres geen onderdeel van de boeken, omdat een auteur meerdere boeken kan schrijven en je die data niet telkens wil kopiëren.
  • Genres – categorieën waar boeken onder vallen, zoals Science Fiction of Non-Fictie.
  • Members – informatie over geregistreerde leden van de bibliotheek, zoals naam, e-mailadres en lidmaatschapsinformatie.
  • Loans – uitleenregistraties, die bijhouden welk lid welk boek heeft geleend, met data voor uitlening en terugbrengen.

Deze collecties zijn met elkaar verbonden via zogeheten references. Elk boek verwijst naar een auteur en genre, en elke uitleenregistratie naar een boek en lid. Ook zijn er al drie vooraf ingestelde gebruikers aanwezig:

Onderaan het bestand vind je de daadwerkelijke data: vier genres, drie boeken en auteurs, twee bibliotheekleden en één uitleenregistratie zijn alvast ingevuld. Deze startdata is meteen beschikbaar in je database en kan via de API-endpoints worden aangevuld, aangepast of verwijderd.

In de volgende secties lees je meer over alle onderdelen die komen kijken bij het opzetten van collecties, velden en het toevoegen van data.